home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audio / alGetParamInfo.z / alGetParamInfo
Encoding:
Text File  |  2002-10-03  |  9.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm))))                                        aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alGetParamInfo - get information about a parameter on a particular audio
  10.      resource
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  14.  
  15.      iiiinnnntttt      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((iiiinnnntttt rrrreeeessss,,,, iiiinnnntttt ppppaaaarrrraaaammmm,,,, AAAALLLLppppaaaarrrraaaammmmIIIInnnnffffoooo ****ppppiiiinnnnffffoooo))));;;;
  16.  
  17.  
  18. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  19.      _r_e_s  is the audio resource (see aaaallllRRRReeeessssoooouuuurrrrcccceeeessss((((3333ddddmmmm))))) to which the given
  20.           parameter applies.
  21.  
  22.      _p_a_r_a_m
  23.           is the parameter about which you desire information.
  24.  
  25.      _p_i_n_f_o
  26.           is a pointer to an ALparamInfo structure allocated by the caller.
  27.  
  28. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  29.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo returns information about the values supported for the
  30.      given parameter _p_a_r_a_m on the given audio resource _r_e_s.  The information
  31.      is returned in an ALparamInfo structure:
  32.  
  33.           typedef struct {
  34.               int resource;   /* the resource */
  35.               int param;      /* the parameter */
  36.               int valueType;  /* type of the whole value (scalar,vector,set...) */
  37.               int maxElems;   /* maximum number of elements */
  38.               int maxElems2;  /* maximum number of elements (2nd dimension) */
  39.               int elementType;     /* type of each element (enum, fixed, resource ...) */
  40.               char name[32];  /* name of the parameter */
  41.               ALvalue initial;     /* initial value */
  42.               ALvalue min;    /* maximum value (range parameters only) */
  43.               ALvalue max;    /* maximum value (range parameters only) */
  44.               ALvalue minDelta;    /* maximum delta between values (range parameters only) */
  45.               ALvalue maxDelta;    /* maximum delta between values (range parameters only) */
  46.               int specialVals;     /* special values not between min & max (range parms only) */
  47.               int operations; /* supported operations */
  48.           } ALparamInfo;
  49.  
  50.  
  51.      The fields are defined as follows:
  52.  
  53.      _r_e_s_o_u_r_c_e is the audio resource to which the parameter applies. _P_a_r_a_m is
  54.      the parameter, as passed in to aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo.
  55.  
  56.      _v_a_l_u_e_T_y_p_e is the aggregate type of the value supported for the parameter.
  57.      It indicates whether or not the value consists of a single element
  58.      (AL_SCALAR_VAL) or multiple elements.  If there are multiple elements, it
  59.      indicates the relationship between the elements: are they an ordered list
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm))))                                        aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      (AL_VECTOR_VAL and AL_STRING_VAL), an unordered set (AL_SET_VAL), or a
  75.      two-dimensional matrix (AL_MATRIX_VAL)?
  76.  
  77.      _m_a_x_E_l_e_m_s indicates the maximum number of elements that the value can have
  78.      on this particular resource. For scalar values, this is always 1. For
  79.      two-dimensional values, the field _m_a_x_E_l_e_m_s_2 is also used, indicating the
  80.      maximum value for the second dimension.
  81.  
  82.      _e_l_e_m_e_n_t_T_y_p_e indicates the type of each element of the value. The
  83.      supported types are: AL_NO_ELEM, indicating that the parameter has no
  84.      associated value; AL_INT32_ELEM and AL_INT64_ELEM, for 32- and 64-bit
  85.      integer values, respectively; AL_FIXED_ELEM, for 64-bit fixed-point
  86.      values; AL_CHAR_ELEM, for 8-bit characters; AL_RESOURCE_ELEM, for values
  87.      which are audio resources; and AL_ENUM_ELEM, for values which are
  88.      enumerated 32-bit integer values.
  89.  
  90.      Element types are divided into two classes: range types and enumerated
  91.      types.  The only two enumerated element types are AL_ENUM_ELEM and
  92.      AL_RESOURCE_ELEM; all the others are considered range types. For
  93.      enumerated types, an application can get the entire set of possible
  94.      values via the aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss call.  For range types, the application can
  95.      examine certain properties about the range of values supported. These
  96.      properties are also returned in the ALparamInfo structure; see below.
  97.  
  98.      The _i_n_i_t_i_a_l field gives the value for this parameter on this resource
  99.      when the audio system is first initialized.
  100.  
  101.      The next fields apply only to range parameters. _m_i_n and _m_a_x give the
  102.      minimum and maximum values, respectively. _m_i_n_D_e_l_t_a and _m_a_x_D_e_l_t_a give the
  103.      minimum and maximum difference between any two adjacent values.
  104.      _s_p_e_c_i_a_l_V_a_l_s describes what "special values" may be supported by the range
  105.      parameter. "Special values" are values outside the range described by
  106.      [min, max] and whose semantics may differ from the values inside that
  107.      range.  The currently supported special values are: AL_NO_CHANGE, which,
  108.      when given as a value for alSetParams, means "Don't change the value of
  109.      this element;" and AL_NEG_INFINITY, which corresponds to a value of
  110.      negative infinity. Each special value has a corresponding bit in
  111.      specialVals which is set if that value is supported. The token for this
  112.      bit is the name of the special value plus "_BIT," e.g. AL_NO_CHANGE_BIT.
  113.  
  114.      Finally, _o_p_e_r_a_t_i_o_n_s describes what operations are supported by this
  115.      parameter on this resource. To determine if an operation is supported,
  116.      see which of the bits AL_GET_OP, AL_SET_OP, AL_EVENT_OP, and AL_QUERY_OP
  117.      are set in _o_p_e_r_a_t_i_o_n_s. If AL_GET_OP is set, the resource supports
  118.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for that parameter. If AL_SET_OP is set, the resource
  119.      supports aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for that parameter. If AL_EVENT_OP is set, the
  120.      resource is capable of generating events when the parameter's value
  121.      changes. If AL_QUERY_OP is set, the resource supports calling
  122.      aaaallllQQQQuuuueeeerrrryyyyVVVVaaaalllluuuueeeessss((((3333ddddmmmm)))) for the parameter.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm))))                                        aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  141.           ALparamInfo pinfo;
  142.  
  143.           /*
  144.            * Grab some information about the gain parameter on this resource.
  145.            * We already know that AL_GAIN always takes a 64-bit fixed-point value, so
  146.            * we can assume that's the type of all the ALvalue fields in "pinfo."
  147.            */
  148.           alGetParamInfo(resource, AL_GAIN, &pinfo);
  149.  
  150.           /* Check to see if this resource supports a gain of minus infinity */
  151.           if (pinfo.specialVals & AL_NEG_INFINITY_BIT) {
  152.               printf("supports negative infinity\n");
  153.           }
  154.  
  155.           printf("min: %lf dB; max: %lf dB; best resolution: %lf dB\n",
  156.               alFixedToDouble(pinfo.min.ll),alFixedToDouble(pinfo.max.ll),
  157.               alFixedToDouble(pinfo.minDelta.ll));
  158.  
  159.  
  160. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  161.      Upon successful completion, aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo returns 0. Otherwise
  162.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo returns -1 and sets an error number which can be retrieved
  163.      with oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))).
  164.  
  165.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmIIIInnnnffffoooo can fail for the following reasons:
  166.  
  167.      AAAALLLL____BBBBAAAADDDD____RRRREEEESSSSOOOOUUUURRRRCCCCEEEE
  168.           _r_e_s_o_u_r_c_e is invalid.
  169.  
  170.      AAAALLLL____BBBBAAAADDDD____PPPPAAAARRRRAAAAMMMM
  171.           _p_a_r_a_m is not supported on the given resource.
  172.  
  173.  
  174. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  175.      oserror(3C), alIntro(3dm), alQueryValues(3dm), alSetParams(3dm),
  176.      alGetParams(3dm)
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.